Skip to main content

Inventory Reporting & Management

Background​

The Inventory Reporting API is useful to create detailed inventory reports of sites, rooms, and devices.

Some examples include device aggregations, device queries, device count, and site & room information.

When you're testing the sample queries below, keep in mind that the GraphQL Explorer is tied to your user's authentication. So, if you're an admin in multiple tenants you'll see data results from those tenants.

If you need to test within a specific tenant, we've exposed an option to use Client Credentials - also known as an API Connection. To select a set of credentials, click the Client Credentials toggle in the upper left hand corner of the page, select the credentials you want to use from the dropdown list, and then continue on with your testing.

Deprecated Queries​

Poly Lens APIs have evolved over recent months as we've worked to optimize the device querying experience. There are two queries which are now deprecated, devices and searchDevices. While both of these queries still "work", they're not as optimized to handle querying large amounts of devices. The new deviceSearch query offers a better way to handle pagination and supports returning results of more than 10k entries.

If you've begun development using either of the prior queries, it would be worth the effort to update your queries to use deviceSearch moving forward. deviceSearch fields use edges and nodes - this is a relational structure that supports pagination and is different than the legacy devices query. deviceSearch also uses the DeviceFindArgs type for argument parameters. You'll see some examples of this structure in our queries below.

Querying Devices​

We'll start by running a query to return information pertaining to devices in our tenant. There are many fields available, but in this example we'll focus on returning the following fields: name, hardwareFamily, softwareVersion, activeApplicationName, hasPeripherals, and connections.

By default, the number of devices returned is 10. However, if you need more than 10 devices returned, you can use the pageSize variable to set a different amount. The minimum is 1 and the maximum is 5000. When you set the number of devices returned you can use the pageInfo fields to return totalCount, countOnPage, nextToken, and hasNextPage - all which are helpful when dealing with pagination. To keep the sample response concise, we'll change the number to 2 in our examples.

Query Devices Using deviceSearch​

See this query in the GraphQL Playground

query allDevices($params: DeviceFindArgs) {
  deviceSearch(params: $params) {
    edges {
      node {
        name
        hardwareFamily
        hardwareModel
        softwareVersion
        activeApplicationName
        hasPeripherals
        connections {
          connected
          allPeripheralsLinked
          name
        }
      }
    }
    pageInfo {
      totalCount
      countOnPage
      nextToken
      hasNextPage
    }
  }
}

Variables​

{
  "params": {
    "pageSize": 2
  }
}

Sample Output From our Query​

{
  "data": {
    "deviceSearch": {
      "edges": [
        {
          "node": {
            "name": "Poly Lens Desktop",
            "hardwareFamily": "Lens App Family",
            "hardwareModel": "Lens Desktop",
            "softwareVersion": "1.0.7",
            "activeApplicationName": null,
            "hasPeripherals": null,
            "connections": [
              {
                "connected": true,
                "allPeripheralsLinked": false,
                "name": "BT700"
              }
            ]
          }
        },
        {
          "node": {
            "name": "Savi 8200 Office Series",
            "hardwareFamily": "Savi Family",
            "hardwareModel": "Savi 8200 Office Series",
            "softwareVersion": "3863",
            "activeApplicationName": null,
            "hasPeripherals": null,
            "connections": []
          }
        }
      ],
      "pageInfo": {
        "totalCount": 3485,
        "countOnPage": 2,
        "nextToken": "MmozNTliZGxslkbnQxODNu",
        "hasNextPage": true
      }
    }
  }
}

Querying Specific Device Details​

The deviceSearch query is incredibly powerful as it provides insight for all the devices in our tenant. You'll likely need to aggregate this data in different ways as you're building your tooling. There are many filters available to use. We'll take a look at a few of these in the next few examples.

Let's say we're building out a page for Room Video devices and want to know which devices are running in Zoom Mode. We can accomplish this by targeting the activeApplicationName field in the deviceSearch query.

For our query we want to know the: device name, serial number, hardware model, activeApplicationName (Provider Mode), activeApplicationVersion (Provider APK Version), and room name & floor they're assigned to.

We'll do this by passing in two filter variables: contains and field. Effectively we're saying for all devices, look at the activeApplicationName field and if it contains "Zoom" return it to me.

Note: The provider name passed into the contains field is case sensitive.

Query Devices Running Zoom Rooms​

See this query in the GraphQL Playground

query zoomDevices($params: DeviceFindArgs) {
  deviceSearch(params: $params) {
    edges {
      node {
        name
        serialNumber
        hardwareModel
        activeApplicationName
        activeApplicationVersion
        room {
          name
          floor
        }
      }
    }

    pageInfo {
      totalCount
      countOnPage
      nextToken
      hasNextPage
    }
  }
}

Variables​

{
  "params": {
    "pageSize": 2,
    "filter": {
      "contains": "Zoom",
      "field": "activeApplicationName"
    }
  }
}

Sample Output From our Query​

A few things to note in the output of our query:

  • The activeApplicationVersion field - The ability to see the application version is helpful for folks managing Poly OS devices running Ecosystem Partner APKs.
  • The nodes returned - We're limiting the countOnPage to 2 items (for conciseness). But if you look at the totalCount you'll see we have 65 items running Zoom Rooms mode.
{
  "data": {
    "deviceSearch": {
      "edges": [
        {
          "node": {
            "name": "DFR StudioX70",
            "serialNumber": "superSecretSerialNumber",
            "hardwareModel": "Studio X70",
            "activeApplicationName": "Zoom Rooms",
            "activeApplicationVersion": "5.13.5.2468",
            "room": {
              "name": "Manta Ray Room",
              "floor": "2"
            }
          }
        },
        {
          "node": {
            "name": "DFR StudioX30",
            "serialNumber": "superSecretSerialNumber",
            "hardwareModel": "Studio X30",
            "activeApplicationName": "Zoom Rooms",
            "activeApplicationVersion": "5.12.0.1972",
            "room": {
              "name": "Salmon Room",
              "floor": "4"
            }
          }
        }
      ],
      "pageInfo": {
        "totalCount": 65,
        "countOnPage": 2,
        "nextToken": "NHU2MTybWpic2Jt",
        "hasNextPage": true
      }
    }
  }
}

Query Devices with the OR: Filter​

If you have an environment containing Poly OS devices running Zoom Rooms and Microsoft Teams, you might want to build a view to display the results based on this criteria. While there are many ways to implement this on the front end, you'll need to build a query to return the devices with this data. You can accomplish this using the OR: filter.

See this query in the GraphQL Playground

query msftAndZoomDevices($params: DeviceFindArgs) {
  deviceSearch(params: $params) {
    edges {
      node {
        name
        serialNumber
        hardwareModel
        activeApplicationName
        activeApplicationVersion
        room {
          name
          floor
        }
      }
    }
    pageInfo {
      countOnPage
      totalCount
      hasNextPage
      nextToken
    }
  }
}

Variables​

{
  "params": {
    "pageSize": 2,
    "filter": {
      "OR": [
        {
          "contains": "Zoom",
          "field": "activeApplicationName"
        },
        {
          "contains": "Microsoft",
          "field": "activeApplicationName"
        }
      ]
    }
  }
}

Sample Output From our Query​

{
  "data": {
    "deviceSearch": {
      "edges": [
        {
          "node": {
            "name": "DFR StudioX30",
            "serialNumber": "superSecretSerialNumber",
            "hardwareModel": "Studio X30",
            "activeApplicationName": "Microsoft Teams",
            "activeApplicationVersion": "1449/1.0.96.2022120503",
            "room": {
              "name": "Trout Room",
              "floor": "3"
            }
          }
        },
        {
          "node": {
            "name": "DFR StudioX70",
            "serialNumber": "superSecretSerialNumber",
            "hardwareModel": "Studio X70",
            "activeApplicationName": "Zoom Rooms",
            "activeApplicationVersion": "5.13.5.2468",
            "room": {
              "name": "Manta Ray Room",
              "floor": "2"
            }
          }
        }
      ],
      "pageInfo": {
        "countOnPage": 2,
        "totalCount": 33,
        "hasNextPage": true,
        "nextToken": "cHknJlcjBueTMwZg=="
      }
    }
  }
}

Query Devices with the OR: & AND: Filters​

If you wanted to take the example above one step further and build the ability to filter your devices on the Provider Mode (activeApplicationName) and the Hardware Model (hardwareModel) you can use the AND: & OR: filters. In the following example we're saying, if the device is running in Zoom Rooms or Microsoft Teams mode and it's a Studio X50, return it to me.

See this query in the GraphQL Playground

query zoomMsftDevices($params: DeviceFindArgs) {
  deviceSearch(params: $params) {
    edges {
      node {
        name
        serialNumber
        hardwareModel
        activeApplicationName
        activeApplicationVersion
        room {
          name
          floor
        }
      }
    }
    pageInfo {
      countOnPage
      totalCount
      hasNextPage
      nextToken
    }
  }
}

Variables​

{
  "params": {
    "pageSize": 2,
    "filter": {
      "AND": [
        {
          "contains": "Studio X50",
          "field": "hardwareModel"
        },
        {
          "OR": [
            {
              "contains": "Zoom",
              "field": "activeApplicationName"
            },
            {
              "contains": "Microsoft",
              "field": "activeApplicationName"
            }
          ]
        }
      ]
    }
  }
}

Sample Output From our Query​

{
  "data": {
    "deviceSearch": {
      "edges": [
        {
          "node": {
            "name": "DFR Studio X50",
            "serialNumber": "superSecretSerialNumber",
            "hardwareModel": "Studio X50",
            "activeApplicationName": "Microsoft Teams",
            "activeApplicationVersion": "1449/1.0.96.2022120503",
            "room": {
              "name": "Sting Ray Room",
              "floor": "2"
            }
          }
        },
        {
          "node": {
            "name": "DFR Studio X50",
            "serialNumber": "superSecretSerialNumber",
            "hardwareModel": "Studio X50",
            "activeApplicationName": "Zoom Rooms",
            "activeApplicationVersion": "5.13.6.2489",
            "room": {
              "name": "Clownfish Room",
              "floor": 3
            }
          }
        }
      ],
      pageInfo": {
        "countOnPage": 2,
        "totalCount": 15,
        "hasNextPage": true,
        "nextToken": "Z2F4eHprc3eG92ZWE0NGt4"
      }
    }
  }
}

The queries above are just a small subset of the Inventory Reporting API's capabilities. If you have specific content requests or questions, reach out to DL-DeveloperSupport@poly.com.